docs: Improve gdk_window_create_similar_image_surface()

The sizes passed are in device pixels and do not take into account the
scaling factor of the window itself. We cannot change the semantics of
the function, so let's at least add a warning for this trap door.

diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index b9c58430e2995fbef6b18b72d5b38d99a65bf339..5e91fcc884ab9fc1402cc10df8e063a6c88009af 100644 (file)
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -10046,6 +10046,25 @@ gdk_window_create_similar_surface (GdkWindow *     window,
  * Initially the surface contents are all 0 (transparent if contents
  * have transparency, black otherwise.)
  *
+ * The @width and @height of the new surface are not affected by
+ * the scaling factor of the @window, or by the @scale argument; they
+ * are the size of the surface in device pixels. If you wish to create
+ * an image surface capable of holding the contents of @window you can
+ * use:
+ *
+ * |[<!-- language="C" -->
+ *   int scale = gdk_window_get_scale_factor (window);
+ *   int width = gdk_window_get_width (window) * scale;
+ *   int height = gdk_window_get_height (window) * scale;
+ *
+ *   // format is set elsewhere
+ *   cairo_surface_t *surface =
+ *     gdk_window_create_similar_image_surface (window,
+ *                                              format,
+ *                                              width, height,
+ *                                              scale);
+ * ]|
+ *
  * Returns: a pointer to the newly allocated surface. The caller
  * owns the surface and should call cairo_surface_destroy() when done
  * with it.